-
Notifications
You must be signed in to change notification settings - Fork 25
/
Code_of_Conduct.md
483 lines (357 loc) · 13.7 KB
/
Code_of_Conduct.md
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
# Code of Conduct
Contents:
1. Naming Conventions
2. Space Usage
3. Variable Type Hint
4. TODO or FIXME Comments
5. Docstring
6. Test Module
7. Git Commit Message
P.S.:Your suggestions are welcome if there is anything which you think needs to be added during the development process.👏
## 1. Naming Conventions
+ Function:Underscore Case, in which using an underscore(_) to separate one word from the next,and the words are generally lowercase.
```python
def foo_name(param):
pass
```
+ Class:Upper Camel Case
```python
class FooName():
pass
```
+ Variable:Underscore Case, in which using an underscore(_) to separate one word from the next,and the words are generally lowercase.
```python
var_name = 3
```
+ Global Variables:Using an underscore(_) to separate the uppercase letter.
```python
# We usually do not use it in a single.py file, but define it at the top level of global_variable.py.
CONT_VAR = 'Geochemistry Py'
```
## 2. Space Usage
+ Equal sign '=' : The use of Spaces around the equals sign for variable assignment and function parameter assignment is different.
```python
# When we assign a value to a variable, there is a space before and after the '='.
var = 1
# When function arguments are called and assigned, Spaces are not required before and after '='.
def foo(param=1):
pass
var = method(param='yes')
# When assigning a default value to a type hint, Spaces are required before and after '='. For what is a type hint, please read the second half of this documentation.
def foo(param: int = 1) -> None:
pass
```
+ Binary operator: There are two cases, whether it is used in the position of the argument. And we have to consider the operator precedence.
```python
# When we use a binary operator in the function argument position, we do not type a Space before or after it.
var = method(param+1)
# When we use it outside the parameter position, we need to type a Space both before and after it.
var = 3 + 2
var += 2
# We only need to add Spaces around the operators with the lowest priority, and nothing else.
var = 3*2 + 1
var = (3+2) * (2+1)
```
+ Annotation: Use **#** with a space followed by a capital letter.
```python
# It prints a word
print('Geochemistry Py')
```
+ Refer to the English format and leave a space after each punctuation mark.
```python
var1, var2 = 1, 2
var3 = method(1, 3, 2)
def foo(name=1, signal='yes'):
pass
```
## 3. Variable Type Hint
+ Type hint: It is a type hint and check for IDEs (e.g. Pycharm) parameters, which can specify the type of the parameter and the return type of the function.
```python
# What is the type hint and what does it do specifically refer to this link :https://sikasjc.github.io/2018/07/14/type-hint-in-python/
# Below is a list of the types that our members might be involved in, along with examples.
# str,int,return
# Function foo takes argument p1 of type str, argument p2 of type int, and returns type str.
def foo(p1: str, p2: int) -> str:
return 'hi'
# list,tuple, set
# Function foo takes argument p1 of type list, and each element in the list is of type int.
# Parameter p2 is passed in of type tuple, and each element in the tuple is of type int.
# Parameter p3 is passed in of type set, and each element in the collection is of type str.
# Function has no return value.
from typing import List, Tuple, Set
def foo(p1: List[int], p2: Tuple[int], p3: Set[str]) -> None:
print(p1)
print(p2)
print(p3)
# dict, nested
# Function foo takes argument p1 of type dict, where the key is of type str and the value of type int.
# Parameter p2 is passed as a list of type, and each element in the list is of type tuple.
from typing import Dict, List, Tuple
def foo(p1: Dict[str: int], p2: List[Tuple[str]]) -> None:
print(p1)
print(p2)
# bool,default value, any type
# Function foo takes parameter p1 as bool, which defaults to True, and parameter p2 can be of any type.
from typing import Any
def foo(p1: bool = True, p2: Any) -> None:
if p1:
print(p2)
# Union: we use it when there is a parameter with multiple possible data types.
# The p1 argument to foo can be of type list or str.
from typing import Union, List
def foo(p1: Union[List, str]) -> None:
pass
# Optional is a simplification of Union. The data type of this parameter can be str in addition to None.
# So Optional[str] is equivalent to Union[str, None], where None is different from the function with the default argument None, which cannot be ignored.
from typing import Optional
def foo(p1: Optional[str] = None) -> str:
return 'Geochemistry Py'
# Tuple: used when returning multiple values.
# Function foo return two values whose types are str and list respectively
from typing import Tuple, List
def foo() -> Tuple[str, List[int]]:
a = 'Geochemistry Py'
b = [1, 2, 3]
return a, b
# pandas.DataFrame, pandas.Series, numpy.ndarray
# The input type of parameter p1 is pandas.DataFrame and type of parameter p2 is pandas.Series,
# The input type of parameter p3 is pandas.Index and type of parameter p4 is numpy.ndarray.
import pandas as pd
import numpy as np
def f2(p1: pd.DataFrame, p2: pd.Series, p3: pd.Index, p4: np.ndarray) -> None:
print(p1)
print(p2)
```
## 4. TODO or FIXME Comments
+ 'TODO' or 'FIXME' should be followed by your name and email to inform others of what to add or change in this code.
+ We can quickly retrieve the number and location of TODOs using an IDE (e.g. Pycharm).
```python
# TODO(Sany hecan@mail2.sysu.edu.cn): Append a new function for ...
# FIXME(Sany hecan@mail2.sysu.edu.cn): Correct this error of ...
```
## 5. Docstring
+ Docstring is a string that appears on the first line of a module, function, class or method definition, and this docstring is used as the \__doc__ property of that object;
+ From a specification point of view, all modules should have docstrings, including the functions and classes introduced from the module;
+ All content types of Docstring are as follows, and not every docstring has to contain all the following content types, just the ones we need.
```python
"""Briefly describe the function the code is intended to achieve.
Parameters
----------
We can explain the data type, data meaning, and source of the parameters defined by the function.
parameter name : data type
(four blanks) Parameter Meaning / Source
temperature : int, str
Temperature at which minerals are formed. From ‘temperature.xlsx’.
density : float
Density of the minerals.
Returns
-------
We can interpret the type and meaning of the data in the output content of the function.
parameter name : data type
(four blanks) Parameter Meaning / Source
temperature : int, str
Temperature at which minerals are formed. From ‘temperature.xlsx’.
References
----------
The source of the code citation can be a literature, website, book, and other sources. When citing multiple documents, you need to indicate [1][2][3] with a serial number and start a separate line.
Format of journal/book : Author + year of publication + title of article + title of journal + volume number + page number
Format of the page/website : author + year and month of publication + title + website name + website link
Note: When the number of authors is greater than two, it can be written as 'first author's name + et al.', e.g. Digne M., et al.
[1] referecne1
[2] reference2
Todo
----
To-do list. When there is more than one to-do list, we need to mark (1)(2)(3) with a serial number and start a new line.
(1) Task1
(2) Task2
Notes
-----
This section includes the requirements for the data, a description of the relevant operations, problems and solutions that may be encountered, and background on the mathematical formulae (using Latex syntax).
When the Note section contains more than one note, it needs to be marked with a serial number (1)(2)(3) or the * symbol, and on a separate line.
(1) Math :
sin(2k\pi + \alpha)= sin\alpha·cos(2k\pi + \alpha)= cos\alpha·tan(2k\pi + \alpha)
(2) Data :
The data should from ‘temperature.xlsx’.
(3) Problem :
When you run,you may meet the problem like...
Examples
--------
Sample doctest tests. Please refer to the Test Module of 《Geochemistry Py - Code Specification》 document for details.
>>> # comments
>>> foo(arg1, arg2)
return value
See also
--------
It identifies the location of other related codes for easy viewing.
When there are multiple related codes, they need to be marked with serial numbers (1)(2)(3) or * symbols, and marked on a separate line.
(1) Code : ’pyrolite.geochem.ind_first’
(2) Code : ’pyrolite.geochem.ind_second’
"""
```
+ Samples
```python
def foo(arg1: int, arg2: int = 1) -> int:
"""The function for what ...
Parameters
----------
arg1 : int
The actual meaning of arg1 ...
arg2 : int, default=1
The actual meaning of arg2 ...
Returns
-------
value : int
The actual meaning of value ...
"""
value = arg1 + arg2
return value
```
## 6. Test Module
+ After finishing the code packaging work, we need to test the code.
+ One way to develop high quality software is to develop test code for each feature and present test samples in both doctest and unittest formats.
+ The test code needs to provide at least 2 or more test cases and try to take into account the boundary conditions of the code.
+ The reason why unit testing is needed, common unit testing approaches and their linkages (Optional), please refer to following links:
+ https://python-course.eu/advanced-python/tests-doctest-unittest.php
+ https://python-course.eu/advanced-python/pytest.php
### (1) Doctest
+ Doctest: Add test code to the **Examples** section of the Docstring of the necessary functions, methods and classes.
+ It enhances the documentation with examples that can be used to confirm that the results of the code are consistent with the documentation.
+ Please refer to the link to use Doctest:https://docs.python.org/3/library/doctest.html
+ Here is the passed example and the results displayed on the command line.
```python
# The passed example
def foo(arg1: int, arg2: int = 1) -> int:
"""The function for what ...
Parameters
----------
arg1 : int
The actual meaning of arg1 ...
arg2 : int, default=1
The actual meaning of arg2 ...
Returns
-------
value : int
The actual meaning of value ...
Examples
--------
>>> # run the python command
>>> foo(2, 7)
9
>>> foo(1, 2)
3
"""
value = arg1 + arg2
return value
if __name__ == "__main__":
# test whether doctest works well, notice that don't cover this part when submitting your code on GitHub
import doctest
doctest.testmod()
```
```python
$ python3 test.py -v
Trying:
foo(2, 7)
Expecting:
9
ok
Trying:
foo(1, 2)
Expecting:
3
ok
1 items had no tests:
__main__
1 items passed all tests:
2 tests in __main__.foo
2 tests in 2 items.
2 passed and 0 failed.
Test passed.
```
+ Here is the failed example and the results displayed on the command line.
```python
# The failed example
def foo(arg1: int, arg2: int = 1) -> int:
"""The function for what ...
Parameters
----------
arg1 : int
The actual meaning of arg1 ...
arg2 : int, default=1
The actual meaning of arg2 ...
Returns
-------
value : int
The actual meaning of value ...
Examples
--------
>>> # run the python command
>>> foo(2, 7)
7
>>> foo(1, 2)
3
"""
value = arg1 + arg2
return value
if __name__ == "__main__":
# see whether doctest works well, notice that don't cover this part when submitting your code on GitHub
import doctest
doctest.testmod()
```
```python
$ python3 test.py -v
Trying:
foo(2, 7)
Expecting:
7
**********************************************************************
File "/Users/can/Documents/sany/work/big_data_geology/geochemistrypy/criteria/docstring/test.py", line 19, in __main__.foo
Failed example:
foo(2, 7)
Expected:
7
Got:
9
Trying:
foo(1, 2)
Expecting:
3
ok
1 items had no tests:
__main__
**********************************************************************
1 items had failures:
1 of 2 in __main__.foo
2 tests in 2 items.
1 passed and 1 failed.
***Test Failed*** 1 failures.
```
### (2) Unittest
+ Test samples are stored in a separate file outside the module to be tested, unlike Doctest, which is stored in the module's Docstring.
+ It is not as easy to use as the Doctest module, but it can provide a more comprehensive set of tests in a separate file.
+ samples:
tbc...
## 7. Git Commit Message
+ One commit for one functionality implementation or one optimization or one bug fix. It is allowed to push multiple commits to the remote codebase with one pull request.
+ Please include the following tags in the beginning of your commit message to make more organized commits and PRs. It would tell exactly what use it is in this commit.
+ `feat`: a new feature is introduced with the changes
+ `fix`: a bug fix
+ `perf`: an existing feature improved
+ `docs`: changes to the documentation
+ `style`: code formatting
+ `refactor`: refactoring production code
+ `revert`: version revertion
+ `chore`: the change of developing tools or assisted tool
+ `test`: adding missing tests, refactoring tests
+ `build`: package the codebase
+ `ci`: continue integration
+ `BREAKING CHANGE`: a breaking API change
Notice: the tags should be lower-case except for `BREAKING CHANGE`.
+ Sample:
```
# Assume that Sany build up a function of drawing the decision boundary for Decision Tree.
# Then he wants to use git commit to append the code changes to his local codebase.
# He will use the command in command line.
git commit -m "feat: add a function to draw the decision boundary for Decision Tree."
```
+ Reference:
+ [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0-beta.2/#specification)